Skip to content

Setup Telegram for adaptor:ex

Before we can use the messenger service Telegram with adaptor:ex, we need to go through a few setup steps.

This works for Telegram in server mode as well as in local mode, but on a server always check if you have the permission to use the Telegram plugin.


Be aware that others with access to the adaptor:ex server can read your phone number and Telegram API credentials (we'll get to that below)! Be responsible with this tool. Telegram will block user accounts if they are found to be spam or flagged. Also, you need to make sure that all data of people communicating with your adaptor:ex instance via telegram is protected and all privacy policies that apply to you are followed. Do not use your private number! Your friends don't know that you are playing with Telegram apps and their data is being processed!

If you have permission and are confident that everything is in order privacy-wise, here's what you need:

  • A Telegram account with associated phone number (be aware that adaptor:ex gets full access to the telegram account via the plugin)
  • access to adaptor:ex
  • an already created game in adaptor:ex

Telegram Setup

Create an account with Telegram

  1. open the game in which we want to use Telegram and select Game > Settings in the upper bar.

  2. there we add the plugin Telegram from the list of inactive plugins and open it. We see 2 fields: api_id and api_hash.

  3. to fill in api_id and api_hash we have to create an account at

  4. there we log in and create the credentials for a client app under API developer tools. More info on this can be found at:

  5. after we have done that we should have gotten our personal api_id and api_hash under API developer tools and can now enter them into the appropriate fields in our adaptor:ex Game Settings:

  6. Then we click on the SAVE button to activate our Game as a Telegram client.

As of now, our adaptor:ex instance is a Telegram client. So kind of like the Telegram app on our smartphone.

Register account phone number in Telegram plugin

  1. Next, we need to register our phone number in our Telegram plugin app. To do this, we add a telegram account in the plugin (the blue plus button at the bottom under ITEMS/ACCOUNTS).

We give the account a good name (for machina eX games we usually take the name of the character whose Telegram account this should be in our game world, here e.g. Alice)

  1. Then we enter the phone number we want to log in with.

This phone number should already be registered with Telegram and we need access to messages from Telegram in the next step. So make sure that you a) are logged in and b) have access with a Telegram app (e.g. on a smartphone) and can receive messages from Telegram to this number!

  1. After entering our phone number, we first click on SAVE, then on the Connect button (the connector icon at the top right of our Telegram Account Settings box).

  2. This should now register our phone number/our Telegram account with Telegram through our plugin Telegram App. So we see (2nd image) a prompt in adaptor:ex asking us for a login code and (1st image) should get a message in Telegram from Telegram to the just registered phone number containing this login code. This works the same way as if we were logging into a Telegram account for the first time with a new app/device.

So we enter the login code in the prompt under code and click send.

  1. If everything worked, we should now get a second message from Telegram that looks something like this image:

This is the Telegram service again making sure that we also know that now a new app has access to the Telegram account with our phone number.

  1. If the led did not turn green try and click on the reload button of our account.

  2. adaptor:ex and the Telegram plugin now receive all messages for this phone number, just like any other Telegram app with which this number is registered.

Telegram plugin connect with LEVEL

But we still need to tell adaptor:ex to which level it should route the incoming messages: For this we go to our Telegram plugin account Alice and click on the Settings button. There we select the option default level and enter a level to which all incoming Telegram messages from numbers that are not currently active in any other level should be routed.

In our example this is the level 'Send_Telegram'

Now whenever a Telegram message is sent to our account Alice, the adaptor:ex Telegram plugin looks if the writing phone number is already in a conversation in one of our levels. If not, it automatically creates a Player Variable with the Telegram data of the writing person and starts a new Session of the Default Level.

There we can then wait for messages from the Player, or send them Telegram messages as Alice, or forward them to other levels and so on ...

This completes the setup of our Telegram plugin app as well as our first account Alice.

We can of course register multiple accounts within our plugin app. But for that we need other phone numbers already registered with Telegram.

Get started

Once everything is set up, here's the first tutorial for a Telegram adventure game: Storytelling with Telegram and adaptor:ex